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CP/M INTERFACE GUIDE 


1. INTRODUCTION 

This manual describes the CP/M system organization including 
the structure of memory, as well as system entry points. The 
intention here is to provide the necessary information required 
to write programs which operate under CP/M, and which use the 
peripheral and disk I/O facilities of the system. 

1.1 CP/M Organization 

CP/M is logically divided into four parts: 

BIOS - the basic I/O system for serial peripheral control 
BDOS - the basic disk operating system primitives 
CCP - the console command processer 
TPA - the transient program area 



The BIOS and BDOS are combined into a single program with a com¬ 
mon entry point and referred to as the FDOS. The CCP is a dis¬ 
tinct program which uses the FDOS to provide a human-oriented 
interface to the information which is cataloged on the diskette. 

The TPA is an area of memory (i.e, the portion which is not used 
by the FDOS and CCP) where various non-resident operating system 
commands are executed. User programs also execute in the TPA, 

The organization of memory in a standard CP/M system is shown in 
Figure 1. 

The lower portion of memory is reserved for system information 
(which is detailed in later sections), including user defined inter¬ 
rupt locations. The portion between tbase and ebase is reserved 
for the transient operating system commands, while the portion 
above ebase contains the resident CCP and FDOS. The last three 
locations of memory contain a jump instruction to the FDOS entry 
point which provides access to system functions. 

1.2 Operation of Transient Programs 

Transient prograuns (system functions and user-defined prograuns) 
are loaded into the TPA and executed as follows. The operator 
communicates with the CCP by typing command lines following each 
prompt character. Each command line takes one of the forms: 
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Figure 1. CP/M Memory Organization 



entry: principal entry point to FX30S is at location 0005 

%^ich contains a JMP to fbase. The address field at 
location 0006 can be used to determine the size of 
available memory, assuming the CCP is being overlsyed. 


Note: The exact addresses for boot, tbase, cbase, fbase, 
and entry vary with the CP/M version (see 
Section 6. for version correspondence)• 




Where <coinmand> is either a built-in command (e.g., DIR or TYPE), 
or the name of a transient command or program. If the <command> 
is a built-in function of CP/M, it is executed immediately; other¬ 
wise the CCP searches the currently addressed disk for a file 
by the name 


<command>•COM 

If the file is found, it is assumed to be a memory image of a 
program vrtiich executes in the TPA, and thus implicitly originates 
at tbase in memory (see the CP/M LOAD command). The CCP loads 
the COM file from the diskette into memory starting at tbase, 
and extending up to address cbase. 

If the <command> is followed by either a <filename> or 
<filename>.<filetype>, then the CCP prepares a file control- 
block (FCB) in the system information area of memory. This FCB 
is in the form required to access the file through the FDOS, and 
is given in detail in Section 3.2. 

The program then executes, perhaps using the I/O facilities 
of the FDOS. If the program uses no FDOS facilities, then the 
entire remaining memory area is available for data used by the 
program. If the FDOS is to remain in memory, then the transient 
program can use only up to location fbase as data.* In any case, 
if the CCP area is used by the tremsient, the entire CP/M system 
must be reloaded upon the transient’s completion. This system 
reload is accomplished by a direct bramch to location "boot" in 
memory. 

The transient uses the CP/M I/O facilities to communicate 
with the operator's console and peripheral devices, including 
the floppy disk subsystem. The I/O system is accessed by passing 
a "function number" and an "information address" to CP/M through 
the address marked "entry" in Figure 1. In the case of a disk 
read, for example, the transient progreun sends the number corres¬ 
ponding to a disk read, along with the address of an FCB, and 
CP/M performs the operation, returning with either a disk read 
complete indication or an error number indicating that the disk 
operation was unsuccessful. The fimction numbers and error in¬ 
dicators are given in detail in Section 3.3. 

1.3 Operating System Facilities 

CP/M facilities which are available to tramsients are divided 
into two categories: BIOS operations, and BDOS primitives. The 
BIOS operations are listed first:** 


* Address "entry" contains a jump to the lowest address in the 
FDOS, and thus "entry+1" contains the first FDOS address \^ich 
cannot be overlayed. 

**The device support (exclusive of the disk subsystem) corres¬ 
ponds exactly to Intel's peripheral definition, including I/O 
port assigment and status byte format (see the Intel mamual 
which discusses the mtellec MDS hardware environment). 
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Read Console Character 
Write Console Character 
Read Reader Character 
Write Punch Character 
Write List Device Character 
Set I/O Status 
Interrogate Device Status 
Print Console Buffer 
Read Console Buffer 
Interrogate Console Status 

The exact details of BIOS access are given in Section 2. The BDOS 

primitives include the following operations: 


Disk System Reset 
Drive Select 
File Creation 
File Open 
File Close 
Directory Search 
File Delete 
File Rename 
Read Record 
Write Record 

Interrogate Available Disks 
Interrogate Selected Disk 
Set DMA Address 

The details of BDOS access are given in Section 3. 


2. BASIC I/O FACILITIES 

Access to common peripherals is accomplished by passing a 
function number and information address to the BIOS. In general, 
the function number is passed in Register C, while the informa¬ 
tion address is passed in Register pair D,£. Note ^at this 
conforms to the PL/M Conventions for parameter passing, and thus 
the following PL/M procedure is sufficient to link to the BIOS 
when a value is returned: 


DECLARE ENTRY LITERALLY *0005H’; /* MONITOR ENTRY V 

M0N2: PROCEDURE (FUNC, INFO) BYTE? 

DECLARE FUNC BYTE, INFO ADDRESS? 

GO TO ENTRY? 


END M0N2? 



MONl; PROCEDURE (FUNC,INFO)y 

DECLARE FUNC BYTE, INFO ADDRESS; 

GO TO ENTRY; 

END MONl 

if no returned value is expected. 

2.1 Direct and Buffered I/O. 

The BIOS entry points are given in Table I. in the case of 
simple character I/O to the console, the BIOS reads the console 
device, and removes the parity bit. The character is echoed back 
to the console, and tab characters (control-I) are expanded to 
tab positions starting at column one and separated by eight char¬ 
acter positions. The I/O status byte takes the form shown in 
Table I, and can be programmatically interrogated or changed. 

The buffered read operation takes advantage of the CP/M line edit¬ 
ing facilities. That is, the program sends the address of a read 
buffer whose first byte is the length of the buffer. The second 
byte is initially empty, but is filled-in by CP/M to the number 
of characters read from the console after the operation (not 
including the terminating carriage-return). The remaining posi¬ 
tions are used to hold the characters read from the console. The 
BIOS line editing functions which are performed during this oper¬ 
ation are given below: 

break - line delete and transmit 

rubout - delete last character typed, and echo 

control-C - system rebout 

control-U - delete entire line 

control-E - return carriage, but do not transmit 
buffer (physical carriage return) 

<cr> - transmit buffer 

The read routine also detects control character sequences other 
than those shown above, and echos them with a preceding "t" 
symbol. The print entry point allows an entire string of symbols 
to be printed before returning from the BIOS. The string is 
terminated by a *'$" symbol. 

2.2 A Simple ExEimple 

As an example, consider the following PL/M procedures and 
procedure calls which print a heading, and successively read 
the console buffer. Each console buffer is then echoed back in 
reverse order: 
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PRINTCHAR: PROCEDURE (B) ; 

/* SEND THE ASCII CHARACTER B TO THE CONSOLE */ 
DECLARE B BYTE; 

CALL MONl(2.B); 

END PRINTCHAR; 


CRLF: PROCEDURE; 

/* SEND CARRIAGE-RETURN-LINE-FEED CHARACTERS */ 
CALL PRINTCHAR (ODH); CALL PRINTCHAR (OAH) ; 

END CRLF; 


PRINT: PROCEDURE (A); 

/* PRINT THE BUFFER STARTING AT ADDRESS A */ 
DECLARE A ADDRESS; 

CALL MONK 9,A) ; 

END PRINT; 

DECLARE PDBUFF (130) BYTE; 


READ: PROCEDURE; 

/★ read console CHARACTERS INTO 'RDBUFF* */ 

RDBUFP=128; /* FIRST BYTE SET TO BUFFER LENGTH */ 

CALL MONl(10,.RDBUFF); 

END READ; 

DECLARE I BYTE; 

CALL CRLF; CALL PRINT (.'TYPE INPUT LINES $’); 

DO WHILE 1; /* INFINITE LOOP-UNTIL CONTROL-C */ 

CALL CRLF; CALL PRINTCHAR ('*'); /* PROMPT WITH ♦/ 
CALL READ; I = RDBUFF(1); 

DO WHILE (I I -1) <> 255; 

CALL PRINTCHAR (RDBUFF(1+2)); 

END; 

END; 


The execution of this program might proceed as follows: 


TYPE INPUT LINES 
♦HELLO, 

OLLEH ^ 

♦WALL WALLA WASH « 
HSAW ALLAW ALLAW 
♦MOM WOW. 

WOW MOM 

♦ tc 


(system reboot) 



TABLE I 

BASIC I/O OPERATIONS 


FUNCTION/ 

NUMBER 

ENTRY 

PARAMETERS 

RETURNED 

VALUE 

TYPICAL 

CALL 

. 

Read Console 

1 

None 

ASCII Character 

I - MON2(1,0) 

Write Console 

2 

ASCII Character 

None 

CALL MONl(2,'A') 

Read Reader 

3 

None 

ASCII Character 

I « MON2(3,0) 

Write Punch 

4 

M 

ASCII Character 

None 

CALL MONl(4, 'B') 

Write List 

5 

ASCII Character 

None 

CALL MONKS, ’C) 

Get I/O Status 

7 

None 

I/O Status Byte 

IOSTAT«MON2(7,0) j 

I 

1 

1 

Set I/O Status 

e 

I/O Status Byte 

None 

" I 

CALL MONl(8,lOSTAT) 

Print Buffer 

9 

Address of 
string termi¬ 
nated by 

None 

CALL MONl(9, .'PRINT 
THIS $') 
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TABLE 

I (continued) 


FUNCTION/ 

ENTRY 

RETURNED 

TYPICAL 

NUMBER 

PARAMETERS 

VALUE 

CALL 

Read Buffer 

Address of 

Read buffer is 

CALL MOHKIO. 

10 

Read Buffer* 

(See Note^) 

filled to maxi- 
mxim length with 
console charac¬ 
ters 

.S0BU7F); 

Interrogate 
Console Ready 

11 

None 

Byte value with 
least signifi¬ 
cant bit « 1 
(true) if con¬ 
sole character 
is ready 

I « MON2(11,0) 


'lote^: 


Read buffer is 


a sequence of memory locations of the form: 



t ^current buffer length 
^Maximian buffer length 


Jote2: 


The I/O status byte is defined as three fields and D 

2b 2b 2b 2b 


MSB 


BCD 


LSB 


requiring two bits each, listed from most significant to least 
significant bit, which define the current device assignment as 
follows: 


D 

sole 


0 TTY 

1 CRT 

2 BATC^ 




C « 

Reader 


TTY 
FAST READER' 




B « 
Punch 


TTY ^ 

PAST PUNCHI 


TTY 

CRT 


J “'■(l 










3. DISK I/O FACILITIES 


The BDOS section of CP/M provides access to files stored on 
diskettes. The discussion which follows gives the overall file 
organization, along with file access mechanisms. 

3.1 File Organization 

CP/M implements a nzuned file structure on each diskette, pro¬ 
viding a logical organization which allows any particular file to 
contain any number of records, from completely empty, to the full 
capacity of a diskette. Each diskette is logically distinct, 
with a complete operating system, disk directory, and file data 
area. The disk file names are in two parts: the <filename> 
which can be from one to eight alphanumeric characters, and the 
<filetype> which consists of zero through three alphanumeric 
characters. The "^filetype^ names the generic category of a par¬ 
ticular file, while the <filen 2 une> distinguishes a paurtici^ar - 
file within the category. The <filetype>s listed below give 
some generic categories which have been established, although 
they are generally arbitrary: 


ASM assembler source file 

ppi^ assembler listing file 

HEX assembler or PL/M machine code 
in "hex'' format 


BAS BASIC Source file 

INT BASIC Intermediate file 

COM Memory image file (i.e., "Command" 

file for transients, produced by LOAD) 

BAK Backup file produced by editor 
(see ED manual) 

$$$ Temporary files created and normally 
erased by editor and utilities 


Thus, the name 

X.ASM 


is interpreted as an assembly language source file by the CCP 
with <filename> X. 

The files in CP/M are organized as a logically contiguous se¬ 
quence of 128 byte records (although the records may not be phys¬ 
ically contiguous on the diskette), which are normally read or 
written in sequential order. Random access is allowed under CP/M 
however, as described in Section 3.4. No particular format with¬ 
in records is assumed by CP/M, although some transients expect 
particular formats: 
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(1) Source files are considered a sequence of 
ASCII characters, where each "line" of the 
source file is followed by carriage-return- 
line-feed characters. Thus, one 128 byte 
CP/M record could contain several logical 
lines of source text. Machine code "hex" 
tapes are also assumed to be in this for¬ 
mat, although the loader does not require 
the carriage-return-line—feed characters. 

End of text is given by the character con- 
trol- 2 , or real end-of-file returned by 
CP/M. 

and 

(2) CC^ files are assumed to be absolute machine 
code in memory image form, starting at tbase 
in memory. In this case, control-z is not 
considered an end of file, but instead is 
determined by the actual space allocated 

to the file being accessed. 

3.2 File Control Block Format 

Each file being accessed through CP/M has a corresponding 
file control block (FCB) which provides name and allocation 
information for all file operations. The FCB is a 33-byte area 
in the transient program's memory space which is set up for each 
file. The FCB format is given in Figure 2. When accessing CP/M 
files, it is the programmer's responsibility to fill the lower 
16 bytes of the FCB, along with the CR field. Normally, the FN 
and FT fields are set to the ASCII <filename> and <filetype>, 
while all other fields are set to zero. Each FCB describes up 
to 16K bytes of a particular file (0 to 128 records of 128 bytes 
each), and, using automatic mechanisms of CP/M, up to 15 addi¬ 
tional extensions of the file can be addressed. Thus, each rcB 
can potentially describe files up to 256K bytes (which is slightly 
larger than the diskette capacity). 

FCB's are stored in a directory area of the diskette, and are 
brought into central memory before file operations (see the OPEN 
and MAKE commands) then updated in memory as file operations pro¬ 
ceed, and finally recorded on the diskette at the termination of 
the file operation (see the CLOSE command). This organization 
makes CP/M file organization highly reliable, since diskette file 
integrity can only be disrupted in the unlikely case of hardware 
failure during update of a single directory entry. 

It should be noted that the CCP constructs an FCB for all 
transients by scanning the remainder of the line following the 
transient name for a <filename> or <filename>.<filetype> com¬ 
bination. Any field not specified is assumed to be all blanks. 

A properly formed FCB is set up at location tfcb (see Section 6), 
with an assumed I/O buffer at tbuff. The transient can use tfcb 
as an address in subsequent input or output operations on this 
file. 


In addition to the default fob %diich is set-up at address tfcb, the 
CCP also constructs a second default fcb at address tfcb-t>16 (i.e./ the 
disk nap field of the fcb at tbase). Thus, if the user types 

PROGNAME X.ZOT Y.ZAP 

the file PRDGNAMB.OOM is loaded to the and the default fcb at >tfeb 
is initialized to the filename X with filetype ZOT. Since the user typed 
a second file name, the 16 byte area beginning at tfcb^ ^ ^^10 Also 
initialized with the filename Y and filetype ZAP. It is the responsibility 
of the prograun to move this second filename and filetype to another area 
(usually a separate file control block) before opening the file which 
begins at tbase, since the open operation will fill the disk map portion, 
thus overwriting the second name and type. 

If no file names were specified in the original coonand, then the 
fields beginning at tfcb and tfcb + 16 both contain blanks (20H). If 
one file name was specified, then the field at tfcb * 16 contains blanks. 
If the filetype is omitted, then the field is assumed to contain blanks. 

In all cases, the CCP translates lower case alphabetics to i^per case 
to be consistent with the CP/M file naming conventions. 

As an added programming convenience, the default buffer at tbuff 
is initialized to hold the entire consnand line past the program name. 
Address tbuff contains the number of characters, and tbuff-M, tbuff+2, 

..., contain the remaining characters up to, but not including, the 
carriage return. Given that the above command has been typed at 
the console, the area beginning at tbuff is set vp as follows: 

tbuff: 

+0 +1 +2 +3 +4 +5 •*•6 +7 -fS +9 -HO -HI •H2 +13 +14 +15 

12 b X . Z 0 T b Y . 2 A P 7 7 ? 


%diere 12 is the number of valid characters (in binary), and b represents 
an ASCII blank. Characters are given in ASCII upper case, with un¬ 
initialized memory following the last valid character. 

Again, it is the responsibility of the program to extract the infor¬ 
mation from this buffer before any file operations are performed since 
the FDOS uses the tbuff area to perform directory functions. 


In a standard CP/H system, tbe following values are assusied: 


boot: OOOOH 
entry: 0005H 
tfcb: OOSCH 
tfcb+16 006CH 
tbuff 0080H 
tbase: 0IOOH 


bootstrap load fwarm start) 

entry point to FDOS 

first default file control block 

second file name 

default buffer address 

base of transient area 
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Figure 2. File Control Block Format 


0 1 2 3 4 5 6 7 8 9 1011 12 13 14 15 16 17 18 19.27 28 29 30 3 1 32 




ET 


FN 


FT EX RC 


DM 


NR 


FIELD 

FCB POSITIONS 

PURPOSE 

ET 

0 

Entry type (currently not used, 
but assumed zero) 

FN 

1-8 

File name, padded with ASCII 
blanks 

FT 

9-11 

File type, padded with ASCII 
blanks 

EX 

12 

File extent, normally set to 
zero 


13-14 

Not used, but assumed zero 

RC 

15 

Record count is current extent 
Size (0 to 128 records) 

DM 

16-31 

Disk allocation map, filled-in 
and used by CP/M 

NR 

32 

Next record number to read or 


write 




3.3 Disk Access Primitives 


Given that a program has properly initialized the PCB's for 
each of its files, there are several operations which can be per¬ 
formed, as shown in Table II. In each case, the operation is 
applied to the currently selected disk (see the disk select oper¬ 
ation in Ted^le II), using the file information in a specific FCB. 
The following PL/M program segment, for example, copies the con¬ 
tents of the file X.Y to the (new) file NEW.FIL: 

DECLARE RET BYTE; 

OPEN; PROCEDURE (A) 

DECLARE A ADDRESS; 

RET=MON2(15,A); 

END OPEN; 

CLOSE: PROCEDURE (A); 

DECLARE A ADDRESS; 

RET=M0N2(16,A); 

END; 

MAKE; PROCEDURE (A); 

DECLARE A ADDRESS; 

RET*MON2(22,A); 

END MAKE; 

DELETE; PROCEDURE (A); 

DECLARE A ADDRESS; 

/* IGNORE RETURNED VALUE ♦/ 

CALL M0N1(19,A); 

END DELETE; 

READBF; PROCEDURE (A); 

DECLARE A ADDRESS; 

RET»MON2(20,A) ; 

END READBF; 

WRITEBF: PROCEDURE (A) ; 

DECLARE A ADDRESS; 

RETSMON2(21,A); 

END WRITEBF; 

ZNIT: PROCEDURE; 

CALL MON1(13,0); 

END INIT; 

/* SET UP FILE CONTROL BLOCKS */ 

DECLARE FCBl (33) BYTE 

INITIAL (0,*X •,*Y *,0,0,0,0), 

INITIAL (0,'NEW '.'PIL’,0.0,0,0); 
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CALL INIT; 

/* ERASE ’NEW-PIL' IF IT EXISTS V 
CALL DELETE (.PCB2); 

/* CREATE*'NEW.FIL* AND CHECK SUCCESS ♦/ 

CALL MAKE (.FCB2); 

IF RET * 255 THEN CALL PRINT (.*N0 DIRECTORY SPACE $'); 
ELSE 

DO; /* FILE SUCCESSFULLY CREATED, NOW OPEN ‘X.Y* */ 
CALL OPEN (.FCBl); 

IF RET » 255 THEN CALL PRINT (.'FILE NOT PRESENT $'); 
ELSE 

DO; /* FILE X.Y FOUND AND OPENED, SET 
NEXT RECORD TO ZERO FOR BOTH FILES */ 

FCBl(32), FCB2(32) * 0; 

/* READ FILE X.Y UNTIL EOF OR ERROR */ 

CALL READBF (.FCBl); /*READ TO BOH*/ 

DO WHILE RET « 0; 

CALL WRITEBF (.FCB2) /♦WRITE PROM 80H*/ 

IF RET » 0 THEN /*GET ANOTHER RECORD*/ 

CALL READBF (.FCBl); ELSE 

CALL PRINT (.'DISK WRITE ERROR $'); 

END; 

IP RET < >1 THEN CALL PRINT (. •“ TRANSFER ERROR $'); 
ELSE 

DO; CALL CLOSE (.PCB2); 

IF RET » 255 THEN CALL PRINT (.'CLOSE ERROR$'); 
END; 

END; 

END; 

EOF 


This program consists of a number of utility procedures for 
opening, closing, creating, and deleting files, as well as two 
procedures for reading and writing data. These utility procedures 
are followed by two FCB's for the input and output files. In 
both cases, the first 16 bytes are initialized to the <filen 2 une> 
and <filetype> of the input and output files. The main program 
first initializes the disk system, then deletes any existing 
copy of **NEW.FIL'* before starting. The next step is to create 
a new directory entry (and empty file) for "NEW.FIL". If file 
creation is successful, the input file "X.Y" is opened. If this 
second operation is also successful, then the disk to disk copy 
can proceed. The NR fields are set to zero so that the first 
record of each file is accessed on subsequent disk I/O operations. 
The first call to READBF fills the (implied) DMA buffer at BOH 
with the first record from X.Y. The loop which follows copies 
the record at BOH to "NEW.FIL" and then reports any errors, or 
reads another 12B bytes from X.Y. This transfer operation con¬ 
tinues until either all data has been transferred, or an error 
condition arises. If an error occurs, it is reported; other¬ 
wise the new file is closed and the program halts. 



TABLE II 



DISK ACCESS 

PRIMITIVES 


PUNCTION/NUMBER 

ENTRY PARAMETERS 

RETURNED VALUE 

TYPICAL CALL 

Lift Head 

12 

None 

None 

Head is lifted from 
current drive 

CALL MON2(12,0) 

Initialize BDOS 
and select disk 
"A" 

Set DMA address 
to 80H 

13 

None 

None 

Side effect is that 
disk A is "logged- 
in" while all others 
are considered "off¬ 
line" 

CALI. MON1(13,0) 

4 

Log-in and 
select disk 

X 

14 

An integer value cor¬ 
responding to the 
disk to log-in: 

A»0, B=lr C=2, etc. 

None 

Disk X is considered 
"on-line" and selec¬ 
ted for subsequent 
file operations 

CALL M0N1(14,1) 

(log-in disk "B") 

Open file 

15 

1 

Address of the FCB 
for the file to be 
accessed 

Byte address of the 

FCB in the directory, 
if found, or 255 if 
file not present. 

The DM bytes are set 
by the BDOS. 

I » HON2(15,.FCB) 

Close file 

16 

Address of an FCB 
which has been pre¬ 
viously created or 
opened 

Byte address of the 
directory entry cor¬ 
responding to the 

FCB, or 255 if not 
present 

I * MON2(16#.PCB) 


TABLE II (continued) 


FUNCTION/NUMBER 

ENTRY PARAMETERS 

RETURNED VALUE 

TYPICAL CALL 

Search for 

17 

file 

i 

Address of FCB con¬ 
taining <filename> 
and <filetype> to 
match* ASCII "?" 
in FCB matches any 
character• 

Byte address of first 
FCB in directory that 
matches input FCB, if 
anyi otherwise 255 
indicates no match. 

I - HON2(17,.FCB) 

Search for 
occurrence 

18 

next 

Same as above, but 
called after func- 
tion 17 (no other 
intermediate BDOS 
calls allowed) 

Byte address of next 

I - HON2(ie,.FCB) 


Delete File Address of FCB con- None 1 • M0N2 (19, .FCB) 

taining <filename> 
and <filetype> of 
file to delete from 
diskette 


nsad Next Record Address of FCB of a 
on successfully OPENed 

file, with NR set 
to the next record 
to read (see note^^) 


0 » successful read I » M0N2(20,.FCB) 

1 « read past end of 

file 

2 » reading unwritten 

data in random 
access 


The I/O operations transfer data to/from address BOH for the next 128 bytes unless 
the address has been altered (see function 26), Further, the NR field of the 

FCB is autOBiatically incremented after the operation. If the NR field exceeds 128, 
the next extent is opened automatically, and the NR field is reset to zero. 


Notej^: 



TABLE II (continued) 


PUNCTION/NUMBER 

ENTRY PARAMETERS 


RETURNED VALUE 

TYPICAL CALL 

Write Next Record 

21 

Same as above, except 

NR is set to the next 
record to write 

0 = 
1 = 

2 = 
255 

successful write 
error in extend¬ 
ing file 

end of disk data 
= no more dir¬ 
ectory space 
(see note 2 ) 

I = MON2(21,.FCB) 


Make File 

Address of FCB with 

Byte address of dir- 

I 

« MON2(22,.FCB) 

22 

<filename> and <file- 

ectory entry alloca- 



type> set. Direc- 

ted to the FCB, or 




tory entry is cre¬ 
ated, the file is 
initialized to empty. 

255 if no directory 
space is available 



Rename FCB 

Address of FCB with 

Address of the dir- 

I 

« MON2(2 3r .FCB) 


old FN and FT in 

ectory entry which 
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first 16 bytes, and 

matches the first 




new FN and FT in 

16 bytes. The 




second 16 bytes 

<fileneune>and <file- 
type> is altered 

255 if no match. 




Note 2 S There are normally 64 directory entries available on each diskette (can be 
expanded to 255 entries), where one entry is required for the primary file, 
and one for each additional extent. 


'ABLE II (continued) 


FUNCTION/NUMBER 

ENTRY PARAMETERS 

RETURNED VALUE 

TYPICAL CALL 

Interrogate log¬ 
in vector 

24 

None 

Byte value with **1** 
in bit positions of 
"on line** disks, 
with least signi¬ 
ficant bit corres¬ 
ponding to disk "A" 

I - HON2(2 4,0) 

Set DMA address 

26 

Address of 128 byte 

DMA buffer 

None 

Subsequent disk I/O 
takes place at spe¬ 
cified address in 
memory 

CALL MON1(26,2000H) 

Interrogate 

Allocation 

27 

None 

Address of the allo¬ 
cation vector for 
the current disk 
(usedby STATUS com¬ 
mand) 

M0N3: PROCEDURE (...) 
ADDRESS; 

A - MON3(27,0); 

Interrogate Drive 
ntanber 

25 

None 

Disk number of currently 
logged disk (i.e., the 
drive which will be used 
for the next disk operation 

/ 

1 

f 

I « M0N2(25»0)| 



1 

17 



i < 1 

. ' ".A* ' . ■ ' , 



3.4 Random Access 


Recall that a single FCB describes up to a 16K segment of a 
(possibly) larger file. Random access within the first 16K seg¬ 
ment is accomplished by setting the NR field to the record number 
of the record to be accessed before the disk I/O takes place. 

Note, however, that if the 128th record is written, then the 
BDOS automatically increments the extent field (EX), and opens 
the next extent, if possible. In this case, the program must 
explicitly decrement the EX field and re—open the previous extent. 
If random access outside the first 16K segment is necessary, 
then the extent number e be explicitly computed, given an absol¬ 
ute record number r as 


or equivalently. 


® “ Li2eJ 

e = SHR(r,7) 


this extent number is then placed in the EX field before the* seg¬ 
ment is opened. The NR value n is then computed as 

n = r mod 128 


or 


n = r AND 7FH. 

When the programmer expects considerable cross-segment accesses, 
it may save time to create an PCB for each of the 16K segments, 
open all segments for access, and compute the relevant FCB from 
the absolute record number r. 


4. SYSTEM GENERATION 

As mentioned previously, every diskette used under CP/M is assianed to 
contain the entire system (excluding transient commands) on the first two 
tracks. The operating system need not be present, however, if the diskette 
is only used as secondary disk storage on drives B, C, ..., since the CP/M 
system is loaded only from drive A. 

The CP/M file system is organized so that an IBM-compatible diskette 
from the factory (or from a vendor which claims IBM cospatibility) looks 
like a diskette with an empty directory. Thus, the user must first copy 
a version of the CP/M system from an existing diskette to the first two 
tracks of the new diskette, followed by a sequence of copy operations, 
using PIP, which transfer the transient command files from the original 
diskette to the new diskette. 
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NOTE; before you begin the C3P/M copy operation, read your Lic en sin g 
Agreeaent* It gives your exact legal obligations when nuiking reproductions 
of CP/M in whole or in part, and specifically requires that you place the 
copyright notice 

Copyright (c), 1976 
Digital Research 

on each diskette which results fron the copy opera t io n * 

4.1. Initializing CP/M from an Existing Diskette 

Tbe first two tracks are placed on a new diskette by running the tran-> 
sient command SYSGCN, as described in the docunent "An Introduction to CP/M 
Features and Facilities." file SYSGEN operation brings the ^/M system from 
an initialized diskette into memory, and then takes the memory image and 
places it on the new diskette. 

Dpon completion of the SYSGEN operation, place the original diskette 
on drive A, and the initialized diskette on drive B. Reboot the system; 
the response should be 


A> 

indicating that drive A is active. Log into drive B by typing 


B: 


and CP/M should respond with 

B> 

indicating that drive B is active. If the diskette in drive B is factory 
fresh, it «rill contain an empty directory. Non-standard diskettes may, 
however, appeair as full directories to CP/M, which can be emptied by typing 

ERA 

idien the diskette to be initialized is active. Do not give the ERA command 
if you wish to preserve files on the new diskette since all files %rill be 
erased with this command. 

After examining disk B, reboot the CF/H system and return to drive A for 
further operations. 

The transient ccnmands are then copied from drive A to drive B using the 
PIP program. The sequence of ccssnands shown below, for exaxqple, copy the 
principal programs from a standard CP/M diskette to the new diskette: 

A>PI^ 

*B;STAT.COM-STAT.OOM^ 

♦B ;PIP .COWPIP .OOM^ 

*B :LOAD. OON>LOAD. COM, 

*B: ED. COM-ED. COM^ 


*B: ASM. CX)M«ASM. OOM^ 

*B; SYSGEN. OOM-SYSGEN . COM. 
*B:DDT.OOM-DDT.OOM^ ^ 

V 

K> 


The user should then log in disk B, and type the ccomand 
DIR 

to ensure that the files itfere transferred to drive B from drive A. The 
various programs can then be tested on drive B to check that they were 
transferred properly. 

Note that the copy operation can be simplified somewhat b^^re^ting, 
a "submit" file which contains the copy connnands. The file could be 
named GEN.SUB, for example, and might contain 

SYSGEN^ 

PIP B:STAT.COM-STAT.COM^ 

PIP B:PIP.COM-PIP.OOM^ 

PIP B:LOAD.COM«LOAD.COM> 

PIP B:ED.COM*ED.OOM^ 

PIP B:ASM.COM«ASM.OOJ^ 

PIP B:SYSGEN.COM-SYSGEN.COM. 

PIP B:DDT.OOM*DDT.COM^ 

The generation of a new diskette from the standard diskette is then done 
by typing siii 5 >ly 

SUBMIT GEl^ 

5. CP/M ENTRY POINT SUMMARY 

The functions shown below summarize the functions of the 
FDOS. The function number is passed in Register C (first para¬ 
meter in PL/M), and the information is passed in Registers D,E 
(second PL/M parcuneter) . Single byte results are returned in 
Register A. If a double byte result is returned, then the high- 
order byte comes back in Register B (normal PL/M return). The 
transient program enters the FDOS through location "entry" (see 
Section 7.) as shown in Section 2. for PL/M, or 

CALL entry • 

in assembly language. All registers are altered in the FDOS. 
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Function 

0 

1 

2 

.3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 
27 


Number 

System Reset 
Read Console 
Write Console 
Read Reader 
Write Punch 
Write List 
(not used) 

Interrogate I/O Status 
Alter I/O Status 
Print Console Buffer 
Read Console Buffer 
Check Console Status 


Information 


ASCII character 

ASCII character 
ASCII character 


I/O Status Byte 
Buffer Address 
Buffer Address 


Lift Disk Head 
Reset Disk System 
Select Disk 
Open Pile 
Close File 
Search First 
Search Next 
Delete File 
Read Record 
Write Record 
Create File 
Rename File 
Interrogate Login 
Interrogate Disk 


Disk ninnber 
FCB Address 

n M 

M » 

H W 

H H 


W W 

W • 

N M 


Set OKA Address DMA Address 

Interrogate Allocation 


Result 


ASCII character 


ASCII character 


I/O Status Byte 


True if character 
Ready 


Completion Code 

H II 

N It 


W II 

«• M 


N 


II 


Login Vector 

Selected Disk 
Number 


Address of Allo¬ 
cation Vector 



6. ADDRESS ASSlOfMENTS 


The standard distribution version of CP/H is organized for an Intel 
MDS microcoaputer developmental system with 16K of main memory, and two 
diskette drives. Larger systems are available in 16K increments, providing 
management of 32K, 48K, and 64K systems (the l^u^gest MDS system is 62K 
since the POM monitor provided with the MDS resides in the top 2K of the 
memory space). For each additional ISK increment, add 4000H to the values 
of cbase and fbase. 


The address assignments are 


boot ■ OOOOH 
tfcb - 005CH 
tbuff* 0080H 
tbase* OlOOH 
cbase* 290OH 
fbase* 3200H 
entry* 0005H 


varm start operation 
default file control block location 
default buffer location 
base of transient program area 
base of console command processor 
base of disk operating system 
entry point to disk system from 
user programs 
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7. SAMPI£ PROGRAMS 

This section contains two sample programs which interface with the CP/M 
operating system. The first program is %^itten in assembly language, and 
is the source program for the OOHP utility. The second program is the CP/M 
LC3AO utility, written in PL/M. 

The assembly language program begins with a number of "equates” for sys¬ 
tem entry points and program constants. The equate 

BDOS EQU 0005B 

for exapple, gives the CP/M entry point for peripheral I/O functions. The 
defualt file control block address is also defined (FCB), along with the 
default buffer address (BUFF) • Note that the program is set up to run at 
location lOOE, %diich is the base of the transient program area. The stack 
is first set-up by saving the entry stack pointer into OLDSP, and resetting 
SP to the local stack. The stack pointer upon entry belongs to the console 
command processor, and need not be saved unless control is to return to the 
OCP upon exit. That is, if the program terminates with a reboot (branch to 
location OOOOH) then the entry stack pointer need not be saved. 

The program then jumps to MAIN, past a number of subroutines which are 
listed below: 

BREAK - when called, checks to see if there is a console 

ctuiracter ready. BREAK is used to stop the listing 
at the console 

PCHAR - print the character which is in register A at the 
console. 

CRLF - send carriage return and line feed to the console 

PNIB - print the hexadecimal value in register A in ASCII 
at the console 

PHEX - print the byte value (two ASCII characters) in 
register A at the console 

ERR - print error flag #n at the console, where n is 

1 if file cannot be opened 

2 if disk read error occurred 

GNB - get next byte of data from the input file. If the 
IBP (input buffer pointer) exceeds the size of the 
input buffer, then another disk record of 128 bytes 
is read. Otherwise, the next character in the buffer 
is returned. IBP is updated to point to the next 
character. 
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The MAIN program then appears, which begins by calling SETUP. The SETUP 
subroutine, discussed below, opens the input file and checks for errors 
If the file is opened properly, the GLCX)P (get loop) label gets control! 

On each successive pass through the GLOOP label, the next data byte 
is fetched using 6NB and save in register B. The line addresses are listed 
every sixteen bytes, so there must be a check to see if the least signi¬ 
ficant 4 bits is rero on each out 5 >ut. If so, the line address is taken 
from registers h and 1, and typed at the left of the line. In all cases, 
the byte which was previously saved in register B is brought back to 
register A, following label NONUM, and printed in the output line. Hie 
cycle through GLOOP continues until an end of file condition is detected 
in DISKR, as described below. Hius, the output lines appear as 

0000 bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb 
0010 bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb hb 


until the end of file. 

The label FINIS gets control upon end of file. CELT is called first 
to return the carriage from the last line output. The CCP stack pointer 
is then reclaimed from OLDSP, followed by a RET to return to the console 
command processor. Note that a JMP OOOOH could be used following the 
FINIS label, which would cause the CP/M system to be brought in again from 
the diskette (this operation is necesseury only if the CCP has been over- 
layed by data areas). 

control block format is then listed (FCBDN ... FCBLN) which 
overlays the fcb at location 05CH %diich is setr^p by the CCP when the 
DUMP program is initiated. That is, if the user types 

DUMP x.y 

then the CCP sets ^p a properly formed fcb at location 05CH for the DUMP 
(or any other) program when it goes into execution. Thus, the SETUP sub¬ 
routine simply addresses this default fcb, and calls the disk system to 
open it. The DISKR (disk read) routine is called whenever GNB needs another 
buffer full of data. The default buffer at location 80H is used, along 
with a pointer (IBP) which counts bytes as they are processed. Normally, 
an end of file condition is taJcen as either an ASCII lAH (control-r), or^ 
an end of file detection by the DOS. Hie file disnp program, however, stops 
only on a DOS end of file. 


FILE DUMP PROGRAM/ READS AN INPUT FILE AND PRINTS IN HEX 


COPYRIGHT (C), DIGITAL RESEARCH, 1975, 1976 
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0100 



ORG 

100H 


0005 

s 

BDOS 

EOU 

0005H 

;DOS ENTRY POINT 

000F 

s 

OPENF 

EOU 

15 

•pile open 

0014 

m 

READF 

EOU 

20 

IREAD FUNCTION 

0002 

m 

TYPEF 

EOU 

2 

•type function 

0001 

m 

CONS 

EQU 

1 

?R£AD CONSOLE 

000B 

m 

BRRF 

EOU 

11 

}BREAK KEY FUNCTION (TRUE IF 

005C 

m 

FCB 

EOU 

5CB 

;FILE CONTROL BLOCK ADDRESS 

0080 

m 

BUFF 

EOU 

80H 

;INPUT DISK BUFFER ADDRESS 



t 

• 

$ 

SET OP 

STACK 


0100 

210000 


LXI 

B,0 


0103 

39 


DAD 

SP 


0104 

220F01 


SHLD 

OLDSP 


0107 

315101 


LXI 

SP,STKTOP 

010A 

C3C401 


JMP 

MAIN 




• 

$ 

VARIABLES 


010D 


IBP: 

DS 

2 

;INPUT BUFFER POINTER 



* 

• 

» 

STACK AREA 


010F 


OLDSP: 

DS 

2 


0111 


STACK: 

DS 

64 


0151 

■ 

STKTOP EQU 

$ 




0 

• 

0 

SUBROUTINES 




BREAK: 

jCHECK 

BREAK KEY 

(ACTUALLY ANY KEY WILL DO) 

0151 

E5D5C5 


PUSH H! 

PUSH D! 

PUSH B; ENVIRONMENT SAVED 

0154 

0E0B 


MVI 

C,BRKF 


£156 

CD0500 


CALL 

BDOS 


0159 

CIDIEI 


POP 61 

POP D1 POP H; ENVIRONMENT RESTORED 

015C 

C9 


RET 





PCHAR: 

;PRINT 

A CHARACTER 

015D 

E5D5C5 


PUSH HI 

PUSH D1 

PUSH B; SAVED 

0160 

0E02 


MVI 

C,TYPES 


0162 

5F 


MOV 

E,A 


0163 

CD0500 


CALL 

BDOS 


0166 

CIDIEI 


POP B1 

POP 01 POP H; 8EST0RED 

0169 

C9 

• 

CRLF: 

RET 



016A 

3E0D 


MVI 

A,0DH 


016C 

CD5D01 


CALL 

PCHAR 


016F 

3E0A 


MVI 

A,0AH 


0171 

CD5D01 


CALL 

PCHAR 


0174 

C9 

• 

$ 

RET 





• 

PNIB: 

jPRINT 

NIBBLE IN REG A 

0175 

E60F 


ANI 

0FH 

;LOW 4 BITS 

0177 

FE0A 


CPI 

10 


0179 

D28101 


JNC 

P10 






; LESS THAN OR EQUAL TO 9 


017C 

C630 


ADI 

'0' 

017E 

f 

C38301 


JMP 

PRN 



? 

• 

f 

GREATER 

OR EQUAL TO 10 

0161 

C637 

P10: 

ADI 

'A' - 10 

0183 

CD5D01 

PRN: 

CALL 

PCHAR 

0186 

C9 


RET 




PHEX: 

?PRINT 

HEX CHAR IN REG A 

0187 

F5 


PUSH 

PSW 

0188 

0F 


RRC 


0189 

0F 


RRC 


018A 

0F 


RRC 


018B 

0F 


RRC 


018C 

CD7501 


CALL 

PNIB ;PRINT NIBBLE 

016F 

FI 


POP 

PSW 

0190 

CD7501 


CALL 

PNIB 

0193 

C9 


RET 




ERR: 

;PRIN1' 

ERROR MESSAGE 

0194 

CD6A01 


CALL 

CRLF 

0197 

3E23 


MV I 

A,'#' 

0199 

CD5D01 


CALL 

PCHAR 

019C 

78 


MOV 

A,B 

019D 

C630 


ADI 

'0' 

019F 

CD5D01 


CALL 

PCHAR 

01A2 

CD6A01 


CALL 

CRLF 

01A5 

C3F701 


JMP 

FINIS 



GNB: 

;GET NEXT BYTE 

01A8 

3A0D01 


LDA 

IBP 

01AB 

FE80 


CPI 

80H 

01AD 

C2B401 


JNZ 

G0 



• 

# 

• 

9 

READ ANOTHER BUFFER 

01B0 

CD1602 

• 

9 

CALL 

DISKR 

01B3 

AF 


XRA 

A 



G0: 

fREAD THE BYTE AT BUFF+REG A 

01B4 

5F 


MOV 

£,A 

01B5 

1600 


MVI 

D,0 

01B7 

3C 


INR 

A 

01B8 

320D01 


STA 

IBP 



• 

t 

POINTER 

IS INCREMENTED 



• 

$ 

SAVE THE CURRENT FILE ADDRESS 

01BB 

£5 


PUSH 

B 

01BC 

218000 


LXI 

B,BUFF 

01BF 

19 


DAD 

D 

01C0 

7E 


MOV 

ArM 



• 

$ 

BYTE IS 

IN THE ACCUMULATOR 



$ 

• 

r 

RESTORE 

FILE ADDRESS AND INCREMENT 

01C1 

El 


POP 

H 

01C2 

23 


INX 

H 

01C3 

C9 


RET 

- 



MAIN: 

; READ 

AND PRINT SUCCESSIVE BUFFERS 

01C4 

CDFF01 


CALL 

SETUP iSET UP INPUT FILE 




01C7 3E80 
01C9 320D01 
01CC 21FFFF 


MVI 

STA 

LXI 


A,80H 

IBP ;SET BUFFER POINTER TO 80H 

H,0FFFFH ;SET TO -1 TO START 


01CF CDA801 
01D2 47 


GLOOP: 


CALL GNB 

MOV B,A 

PRINT HEX VALUES 


01D3 7D 
0104 E60F 
0106 C2EB01 

0109 CD6A01 


01OC CO5101 
01OF 0P 
01E0 DAF701 


CHECK FOR LINE FOLD 
MOV A,L 

ANI 0FH ;CHECK LOW 4 BITS 

JNZ NONUM 

PRINT LINE NUMBER 
CALL CRLF 

CHECK FOR BREAK KEY 
CALL BREAK 

RRC 

JC FINIS ;DON'T PRINT ANY MORE 


01E3 

7C 


MOV 

A,H 

01E4 

CD8701 


CALL 

PH EX 

01E7 

70 


MOV 

A,L 

01E8 

CD8701 

NONUM: 

CALL 

PHEX 

01EB 

3E20 


MVI 

A, ' 

01ED 

CO5O01 


CALL 

PCHAR 

01F0 

78 


MOV 

A,B 

01F1 

CD8701 


CALL 

PHEX 

01F4 

C3CF01 


JMP 

GLOOP 



EPSA: 

;ENO 

PSA 




• 

9 

END OP INPUT 



FINIS: 



01F7 

CD6A01 


CALL 

CRLF 

01FA 

2A0F01 


LHLD 

OLOSP 

01FD 

F9 


SPHL 


01FE 

C9 

• 

$ 

RET 




• 

9 

• 

9 

FILE 

CONTROL BLOCK DEFINITIONS 

005C 

B 

FCBDN 

EOU 

FCB-)-0 ;DISR NAME 

0050 

B 

FCBFN 

EQU 

FCB+1 ;FILE NAME 

0065 

B 

FCBFT 

EOU 

FCB+9 ;DISK FILE TYPE 

0068 

it 

PCBRL 

EOU 

PCB+12 jFILE'S CURRENT 

006B 

B 

FCBRC 

EOU 

FCB+15 ;FILE'S RECORD 

007C 

B 

FCBCR 

EOU 

FCB+32 ;CURRENT (NEXT) 

0070 

B 

FCBLN 

; 

EOU 

FCB+33 ?FCB LENGTH 



• 

SETUP: 

;SET 

UP FILE 




OPEN 

THE FILE FOR INPUT 

01FF 

115C00 


LXI 

D,FCB 

0202 

0E0F 


MVI 

CpOPENF 

0204 

CD0500 


CALL 

BOOS 



• 

9 

CHECK 

FOR ERRORS 

0207 

FEFF 


CPI 

255 

0209 

C21102 


JNZ 

OPNOK 






j BAD OPEN 


020C 

0601 

MVI 

B,! 

9OPEN ERROR 

020E 

CD9401 

CALL 

ERR 




7 

OPNOK: ;OPEN 

IS OK. 


0211 

AF 

XRA 

A 


0212 

327C00 

STA 

FCBCR 


0215 

C9 

RET 





DISKR: ;READ 

DISK FILE 

RECORD 

0216 

E5D5C5 

PUSH HI PUSH D1 

PUSH B 

0219 

115C00 

LXI 

D,FCB 


021C 

0E14 

MVI 

C.READF 


021E 

CD0500 

CALL 

.BDOS 


0221 

CIDIEI 

POP BI 

POP D1 POP B 

0224 

FE00 

CPI 

0 

TCHECK FOR ERRS 

0226 

C8 

RZ 





; MAY BE 

EOF 


0227 

FE01 

CPI 

1 


0229 

CAF701 

JZ 

FINIS 


022C 

0602 

MVI 

B,2 

;DISK READ ERROR 

022E 

CD9401 

CALL 

ERR 


0231 


END 
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The PL/M program whi^ follo%rs implements the CP/M LOAD utility. The 
function is as follows. The user types 

LOAD filename^ 

If filename.BEX exists on the diskette, then the LOAD utility reads the "hex'* 
formatted machine code file and produces the file 

filename. COM 

«diere the COM file contains an absolute memofy image of the machine code, 
ready for load and execution in the TPA. Zf the file does not appear on 
the disJcette, the LOAD program types 

SOURCE IS READER 

and reads an Addmaister paper tape reader which contains the hex file. 

The LOAD program is set up to load and run in the TPA, and, upon com¬ 
pletion, return to the CCP without rebooting the system. Thus, the pro¬ 
gram is constructed as a single procedure called LOADCOM which takes the 
form 


OFAB: 

LOADCOM: PROCEDURE; 

^ /* LIBRARY PROCEDURES V 

I MOMl: ... 

/* END LIBRARY PROCEDURES */ 

MOVE: ... 

GETCBAR: ... 

PRINTNIB: ... 

PRIMTBEX: ... 

PRINTADDR: ... 

RELOC: ... 

SETMEM: 

REAEKEX: 

READBYTE: 

READCS: 

MAXEDOUBLE: 

DZAGNOSE: 

RELOC; 

DECLARE STACK(16) ADDRESS, SP ADl^ESS; 

SP • STACKPTR; STACKPTR • .STACK(LENGTH(STACK) 


CALL RELOC; 


\ STACKP TR " SP; 
V RETURN 0; 

END LOADCOM; 


; 

EOF 


; 
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The label OFAH at the beginning sets the origin of the ccnpilation to OFAH, 
which causes the first 6 bytes of the compilation to be ignored when loaded 
(i.e., the TPA starts at location lOOH and thus OFAH,...,OFFH are deleted 
from the COM file). In a PL/M compilation, these 6 bytes are used to set up 
the stack pointer and branch around the subroutines in the program. In this 
case, there is only one subroutine, called LOADCOM, which results in the 
following machine memory image for LOAD 

OFAH; LXI SP,plmstack jSET SP TO DEFAULT STAC3C 
OFEH: JMP pastsubr iJUMP AROUND LOADCX)M 

lOOH: beginning of LOADCOM procedure 

• • • • 

end of LOADCOM procedure 

RET 

pastsubr: 

£I 

HLT 

Since the machine code between OFAH and OFFH is deleted in the load, 
execution actually begins at the top of LOADCOM. Note, however, that 
the initialisation of the SP to the defaxilt stack has also been deleted; 
thus, there is a declaration and initialisation of an explicit stack and 
stack pointer before the call to RELOC at the end of LOADCOM. This is 
necessary only if we wish to return to the CCP without a reboot operation; 
otherwise the origin of the program is set to lOOH, the declaration of 
LOADCOM as a procedure is not necessary, and termination is accomplished 
by simply executing a 

GO TO OOOOH; 

at the end of the program. Note also that the overhead for a system re¬ 
boot is not great (approximately 2 seconds), but cam be bothersome for 
system utilities which are xised quite often, and do not need the extra 
space. 

The procedures listed in LOADCOM as "library procedures" are a standard 
set of PL/M subroutines which are useful for CP/M interface. The RELOC 
procedure contains several nested subroutines for locad fianctions, and 
actuaU-ly performs the load operation when called from LOADCOM. Control 
initially staurts on line 327 where the stackpointer is saved and re-initialized 
to the local stack. The default file control block name is copied to 
another file control block (SFCB) since two files may be open at the same 
time. The program then calls SEARCH to see if the HEX file exists; if not, 
then the high speed reader is used. If the file does exist, it is opened for 
input (if possible). The filetype COM is moved to the default file control 
block area., and any existing copies of filename.COM files are removed from 
the diskette before creating a new file. The MAKE operation creates a new 
file, and, if successful, RELOC is called to read the HEX file and produce 
the COM file. At the end of processing by RELOC, the COM file is closed 
(line 350). Note that the HEX file does not need to be closed since it 
was ppenod for input only. The data %«:itten to a file is not permanently 
recorded until the file is successfully closed. 



Disk input charneters are read through the procedure GETCHAR on line 
137. Although the DMA facilities of CP/M could be used here, the GETCHAR 
procedure instead uses the default bxiffer at location SOB and moves each 
buffer into a vector called SBUFF (source buffer) as it is read. On exit, 
the GETCHAR procedure returns the next input character and updates the 
source buffer pointer (SBP) • 

The SETMEM procedure on line 191 performs the opposite function from 
GETCHAR. !Che SETMEM procedure maintains a buffer of loaded machine code 
in pure binary form which acts as a ^window” on the loaded code. Zf there 
is an attempt by RELOC to %n:ite below this %rindow, then the data is ignored. 
Zf the data is within the window, then it is placed into MBUFF (mestory 
buffer) . Zf the data is to be placed above this window, then the idndow 
is moved up to the point where it %fOuld include the data address by %nriting 
the memory image successively (by 128 byte buffers), and moving the base 
address of the window. Using this technique, the prograsmer can recover 
from chec)cs;sD errors on the high-speed reader by stopping the reader, 
rewinding the tape for seme distance, then restarting LOAD (in this case, 
LOADing is resumed by interrupting %iith a NOP instruction) . Again, the “ 
SETMEM procedure uses the default buffer at location SOB to perform the 
disk output by moving 128 byte segments to SOB through (3FFB before each 
%c:ite. 



00001 1 
00002 1 
00003 1 

00004 1 

00005 1 

00006 1 
00007 1 

00008 1 
00009 1 

00010 2 
00011 2 
00012 2 
00013 2 

ESS */ 
00014 2 

00015 2 

00016 2 

/ 

00017 2 

00018 2 
00019 2 

00020 2 
00021 2 
00022 2 
*/ 

00023 2 

00024 2 

ROM THE 
00025 2 

S THE MACH 
00026 2 
*/ 

00027 2 

****** */ 
00028 2 
00029 2 

00030 3 

00031 3 

00032 3 

00033 3 

00034 2 

00035 2 

00036 3 

00037 3 

00038 3 

00039 3 

00040 2 

00041 2 

00042 3 

00043 3 

00044 3 

00045 2 

00046 2 

00047 2 

00048 2 

00049 2 

00050 2 




0FAH: DECLARE BDOS LITERALLY '0005H'; 
/* TRANSIENT COMMAND LOADER PROGRAM 




COPYRIGHT (C) DIGITAL RESEARCH 
JUNE, 1975 


LOADCOM: PROCEDURE BYTE; 

DECLARE FCBA ADDRESS INITIAL(5CH); 

DECLARE FCB BASED FCBA (33) BYTE; 

DECLARE BUFFA ADDRESS INITIAL(80H), /* I/O BUFFER ADDR 

BUFFER BASED BUFFA (128) BYTE; 

DECLARE SFCB(33) BYTE, /* SOURCE FILE CONTROL BLOCK * 

BSIZE LITERALLY '1024', v. 

EOFILE LITERALLY 'lAH', 

SBUFF(BSIZE) BYTE /* SOURCE FILE BUFFER */ 

INITIAL(EOFILE), 

RFLAG BYTE, /* READER FLAG */ 

SBP ADDRESS; /* SOURCE FILE BUFFER POINTER 


/* LOADCOM LOADS TRANSIENT COMMAND PILES TO THE DISK F 
CURRENTLY DEFINED READER PERIPHERAL. THE LOADER PLACE 
CODE INTO A FILE WHICH APPEARS IN THE LOADCOM COMMAND 
/* **************** library PROCEDURES FOR DISKIO ******* 


MONl: PROCEDURE(F,A); 

DECLARE F BYTE, 

A ADDRESS; 

GO TO BDOS; 

END MONl; 

MON2: PROCEDURE(F,A) BYTE; 

DECLARE F BYTE, 

A ADDRESS; 

GO TO BDOS; 

END MON2; 

READRDR; PROCEDURE BYTE; 

/* READ CURRENT READER DEVICE */ 
RETURN MON2(3,0); 

END READRDR; 

DECLARE 

TRUE LITERALLY '1', 

FALSE LITERALLY '0', 

FOREVER LITERALLY 'WHILE TRUE', 
CR LITERALLY '13', 


00051 2 

00052 2 

00053 2 

00054 2 

00055 3 

00056 3 

00057 3 

00056 2 

00059 2 

00060 3 

00061 3 

00062 3 

00063 2 

00064 2 

00065 3 

00066 3 

00067 3 

00068 3 

00069 3 

00070 3 

00071 2 

00072 2 

00073 2 

00074 2 

00075 3 

00076 3 

00077 2 

00076 2 

00079 3 

00080 3 

00081 3 

00082 2 
00083 2 

00084 3 

00085 3 

00086 3 

00087 2 

00088 2 
00089 3 

00090 3 

00091 3 

00092 2 

00093 2 

00094 3 

00095 3 

00096 3 

00097 2 

00098 2 

00099 3 

00100 3 

00101 2 
00102 2 
00103 3 

00104 3 

00105 3 

00106 2 
00107 2 

00108 3 

00109 3 

00110 3 


LF LITERALLY '10 r 
WHAT LITERALLY '63'? 

PRINTCHAR: PROCEDURE(CHAR)? 33 

DECLARE CHAR BYTE; 

CALL MONl(2rCHAR); 

END PRINTCHAR? 

CRLF: PROCEDURE? 

CALL PRINTCHAR(CR)? 

CALL PRINTCHAR(LF)? 

END CRLF; 

PRINT: PROCEDURE(A)? 

DECLARE A ADDRESS? 

/* PRINT THE STRING STARTING AT ADDRESS A UNTIL THE 
NEXT DOLLAR SIGN IS ENCOUNTERED */ 

CALL CRLF ? 

CALL MONK9,A) ? 

END PRINT? 

DECLARE DCNT BYTE? 

INITIALIZE: PROCEDURE? 

CALL MON1(13,0)? 

END INITIALIZE? 

SELECT; PROCEDURE(D) ? 

DECLARE D BYTE? 

CALL MONK 14,D) ? 

END SELECT? 

OPEN; PROCEDURE(FCB)? 

DECLARE FCB ADDRESS; 

DCNT « MON2(15,FCB)? 

END OPEN? 

CLOSE; PROCEDURE(FCB)? 

DECLARE FCB ADDRESS? 

DCNT « MON2(16,FCB)? 

END CLOSE? 

SEARCH: PROCEDURE(FCB)? 

DECLARE FCB ADDRESS; 

DCNT « MON2(17,FCB) 

END SEARCH? 

SEARCHN: PROCEDURE; 

DCNT « MON2(18,0); 

END SEARCHN? 

DELETE: PROCEDURE(FCB); 

DECLARE FCB ADDRESS; 

CALL MONK19,FCB) ? 

END DELETE ? 

DISKREAD: PROCEDURE(FCB) BYTE? 

DECLARE FCB ADDRESS? 

RETURN MON2(20,PCB)? 

END DISKREAD? 



00111 2 
00112 2 
00113 3 

00114 3 

00115 3 

00116 2 
00117 2 

00118 3 

00119 3 

00120 3 

00121 2 
00122 2 
00123 3 

00124 3 

00125 3 

00126 2 
00127 2 

***** */ 
00128 2 
00129 2 

00130 3 

00131 3 

00132 3 

00133 3 

00134 4 

00135 3 

00136 2 

00137 2 

00138 3 

00139 3 

00140 3 

00141 3 

00142 3 

00143 3 

00144 3 

00145 3 

00146 4 

00147 4 

ROR$') ; 
00148 5 

00149 5 

00150 5 

00151 4 

00152 3 

00153 3 

00154 2 

00155 2 

00156 2 

00157 2 

00158 2 

00159 3 

00160 3 

00161 3 
00162 3 
00163 2 

00164 2 

00165 3 

00166 3 
00167 3 

00168 2 


DISKWRITE; PROCEDURE(PCB) BYTE; 
DECLARE FCB ADDRESS; 

RETURN MON2(21,FCB); 

END DISKWRITE; 


MAKE; PROCEDURE(FCB); 

DECLARE FCB ADDRESS; 
DCNT * MON2(22,FCB); 
END MAKE; 

RENAME: PROCEDURE(FCB); 
DECLARE FCB ADDRESS; 
CALL M0N1(23,FCB); 
END RENAME; 






END OF LIBRARY PROCEDURES 


******** 


MOVE; PROCEDURE(S,D,N); 

DECLARE (S,D) ADDRESS, N BYTE, 

A BASED S BYTE, B BASED D BYTE; 

DO WHILE (N;-N-l) <> 255; 

B « A; S«S+1; D«D+1; 

END; 

END MOVE; 

GETCHAR: PROCEDURE BYTE; 

/* GET NEXT CHARACTER */ 

DECLARE I BYTE; 

IF RFLAG THEN RETURN READRDR; 

IF (SBP :« SBP+1) <« LAST(SBUFF) THEN 
RETURN SBUFF(SBP); 

/* OTHERWISE READ ANOTHER BUFFER PULL */ 

DO SBP » 0 TO LAST(SBUFF) BY 128; 

IF (I:«DISKREAD(.SFCB)) « 0 THEN 

CALL MOVE(80H,.SBUFF(SBP),80H); ELSE 

DO; IF lOl THEN CALL PRINT(.'DISK READ ER 

SBUFF(SBP) « EOFILE; 

SBP « LAST(SBUFF); 

END; 

END; 

SBP « 0; RETURN SBUFF; 

END GETCHAR; 

DECLARE 

STACKPOINTER LITERALLY 'STACKPTR'; 


PRINTNIB: PROCEDURE(N); 

DECLARE N BYTE; 

IP N > 9 THEN CALL PRINTCHAR(N+'A'-10); ELSE 
CALL PRINTCHAR(N+'0'); 

END PRINTNIB; 

PRINTHEX: PROCEDURE(B); 

DECLARE B BYTE; 

CALL PRINTNIB(SHR(B,4)); CALL PRINTNIB(B AND 0PH); 
END PRINTHEX; ' 


00169 

2 

PRINTADDR: PROCEDURE(A); 




00170 

3 

DECLARE A ADDRESS; 




00171 

3 

CALL PRINTHEX(HIGH(A)) 

} CALL 

PRINTHEX(LOW(A)); 

00172 

3 

END PRINTADDR; 




00173 

2 





00174 

2 





00175 

2 

/* INTEL HEX FORMAT LOADER •/ 


00176 

2 





00177 

2 

RELOC: PROCEDURE; 




00178 

3 

DECLARE (RL, CS, RT) 

BYTE; 


00179 

3 

DECLARE 




00180 

3 

LA ADDRESS,. 

y* 

LOAD 

ADDJRESS */ 

00181 

3 

TA ADDRESS, 

/* 

TEMP 

ADDRESS ♦/ 

00182 

3 

SA ADDRESS, 

/* 

START 

ADDRESS */ 

00183 

3 

FA ADDRESS, 

/* 

FINAL 

ADDRESS */ 

00184 

3 

NB ADDRESS, 

/* 

NUMBER OF BYTES LOADED * 

00185 

3 

SP ADDRESS, 

/* 

STACK 

POINTER UPON ENTRY 


oc */ 
00186 
00187 
00188 
00189 
00190 
00191 
00192 
*/ 


35 


/ 


h6UFF(256) BYTE, 

P BYTE, 

L ADDRESS; 

SETMEM: PROCEDURE(B); 

/★ SET MBUFF TO B AT LOCATION LA MOD LENGTH(MBUFF) 


00193 4 

00194 4 

00195 4 

GRAPH */ 
00196 4 

00197 5 

00198 6 

00199 5 

00200 5 

00201 5 

00202 5 

00203 6 

00204 6 

00205 6 

00206 6 
00207 5 

00208 4 

00209 4 

00210 3 

00211 3 

00212 4 

00213 4 

00214 4 

00215 4 

00216 4 

00217 4 

00218 3 

00219 3 

00220 4 

00221 4 

00222 4 

00223 3 

00224 3 

00225 4 


DECLARE (B,I) BYTE; 

IF LA < L THEN /* MAY BE A RETRY */ RETURN; 

DO WHILE LA > L + LAST(MBUFF); /* WRITE A PARA 

DO I • 0 TO 127; /* COPY INTO BUFFER */ 
BUFFER(I) « MBUFF(LOW(L)); L « L + 1; 

END; 

/♦ WRITE BUFFER ONTO DISK */ 

P ■ P + 1; 

IF DISKWRITE(FCBA) <> 0 THEN 

DO; CALL PRINT(.'DISK WRITE ERROR$'); 

HALT; 

/* RETRY AFTER INTERRUPT NOP */ 

L » L - 128; 

END; 

END; 

MBUFF (LOW (LA) ) » B; 

END SETMEM; 

READHEX: PROCEDURE BYTE; 

/* READ ONE HEX CHARACTER PROM THE INPUT */ 

DECLARE H BYTE; 

IF (H GETCHAR) - '0' <« 9 THEN RETURN H - '0'; 
IF H - 'A' > 5 THEN GO TO CHARERR; 

RETURN H - 'A' + 10; 

END READHEX; 

READBYTE: PROCEDURE BYTE; 

/* READ TWO HEX DIGITS */ 

RETURN SHL(READHEX,4) OR READHEX; 

END READBYTE; 

READCS: PROCEDURE BYTE; 

/-* READ BYTE WHILE COMPUTING CHECKSUM */ 



t)0226 4 

00227 4 

00228 4 

00229 4 

00230 3 

00231 3 

00232 4 

S */ 

00233 4 

00234 4 

00235 4 

00236 3 

00237 3 

00238 4 

00239 4 

00240 4 

00241 4 

00242 5 

• 

'00243 5 

00244 5 

00245 4 

00246 4 

00247 4 

00248 4 

00249 4 

00250 4 

00251 4 

00252 4 

00253 5 

00254 5 

00255 5 

00256 4 

00257 4 

00258 4 

00259 3 

00260 3 

00261 3 

00262 3 

00263 3 

00264 3 

00265 3 

*/ 

00266 3 

00267 3 

KTERED */ 
00268 3 

00269 4 

00270 4 

00271 4 

00272 3 

00273 3 

00274 3 

00275 3 

00276 3 

00277 3 

00278 3 

00279 4 


DECLARE B BYTE; 

CS « CS + (B :« READBYTE); 

RETURN B; 

END READCS; 36 

MAKE$DOUBLE: PROCEDURE(H,L) ADDRESS; 

/* CREATE A BOUBLE BYTE VALUE FROM TWO SINGLE BYTE 

DECLARE (H,L) BYTE; 

RETURN SHL(DOUBLE(H),8) OR L; 

END HAKE$DOUBLE; 

DIAGNOSE: PROCEDURE; 

DECLARE M BASED TA BYTE; 

NEWLINE: PROCEDURE; 

CALL CRLF; CALL PRINTADDP(TA); CALL PRINTCHAR{': 

CALL PRINTCHAR(' '); 

END NEWLINE; 

/* PRINT DIAGNOSTIC INFORMATION AT THE CONSOLE */ 

CALL PRINT(.[LOAD ADDRESS $'); CALL PRINTADDR(TA) 
CALL PRINT(.'ERROR ADDRESS $'); CALL PRINTADDR(LA) 

CALL PRINT(.'BYTES READ:$'); CALL NEWLINE; 

DO WHILE TA < LA; 

IF (LOW(TA) AND 0FH) * 0 THEN CALL NEWLINE; 

CALL PRINTHEX(MBUFF(TA-L)); TA«TA+1; 

CALL PRINTCHAR(' '); 

END; 

CALL CRLF; 

HALT; 

END DIAGNOSE; 


/* INITIALIZE V 
SA, FA, NB - 0; 

SP • STACKPOINTER; 

P • 0; /* PARAGRAPH COUNT */ 

TA,LA,L * 100H; /* BASE ADDRESS OF TRANSIENT ROUTINES 

IF FALSE THEN 

CHARERR: /* ARRIVE HERE IF NON-HEX DIGIT IS ENCOU 

DO; /* RESTORE STACKPOINTER */ STACKPOINTER « SP; 
CALL PRINT(.'NON-HEXADECIMAL DIGIT ENCOUNTERED $') 

CALL DIAGNOSE; 

END; 


/* READ RECORDS UNTIL :00XXXX IS ENCOUNTERED */ 

DO FOREVER; 

/* SCAN THE : */ 

DO WHILE GETCHAR <> 

END; 


00280 

4 



00281 

4 


/* SET CHECK SOM TO ZERO, AND SAVE THE RECORD LENG 

TH */ 




00282 

4 


CS « 0; 

00283 

4 


/* MAY BE THE END OF TAPE */ 

00284 

4 


IF (RL :« READCS) « 0 THEN 

00285 

4 


GO TO FIN; 

00286 

4 


NB • NB + RL; 

00287 

4 



00288 

4 


TA, LA » MAKE$DOOBLE(READCS,READCS); 

00289 

4 


IF SA « 0 THEN SA - LA; 

00290 

4 



00291 

4 



00292 

4 


/* READ THE RECORD TYPE (NOT CURRENTLY USED) */ 

00293 

4 


RT » READCS; 

00294 

4 



00295 

4 


/* PROCESS EACH BYTE */ 

00296 

4 


DO WHILE (RL :« RL - 1) <> 255; 

00297 

4 


CALL SETMEM(READCS); LA « LA+1; 

00298 

5 


END; 

00299 

4 


IF LA > FA THEN FA « LA - 1; 

00300 

4 



00301 

4 


/* NOW READ CHECKSUM AND COMPARE */ 

00302 

4 


IF CS + READSYTE <> 0 THEN 

00303 

4 


DO; CALL PRINT ^.'CHECK SUM. ERROR 

00304 

5 


CALL DIAGNOSE; 

00305 

5 


END; 

00306 

4 


END; 

00307 

3 



00308 

3 


FIN: 

00309 

3 


/* EMPTY THE BUFFERS */ 

00310 

3 


TA » LA; 

00311 

3 


DO WHILE L < TA; 

00312 

3 


CALL SETMEM (0) ; LA « LA-i-l; 

00313 

4 


END; 

00314 

3 


/* PRINT FINAL STATISTICS */ 

00315 

3 


CALL PRINT(,'FIRST ADDRESS $'); CALL PRINTADDR(SA); 

00316 

3 


CALL PRINT(,'LAST ADDRESS $'); CALL PRINTADDR(FA); 

00317 

3 


CALL PRINT(.'BYTES READ $'); CALL PRINTADDR(NB); 

00318 

3 


CALL PRINT(•'RECORDS WRITTEN $'); CALL PRINTHEX(P); 

00319 

3 


CALL CRLF; 

00320 

3 



00321 

3 


END RELOC; 

00322 

2 



00323 

2 

/* 

ARRIVE HERE FROM THE SYSTEM MONITOR, READY TO READ THE 

HEX TAPE 



00324 

2 



00325 

2 

/* 

SET DP STACKPOINTER IN THE LOCAL AREA */ 

00326 

2 

DECLARE STACK(16) ADDRESS, SP ADDRESS; 

00327 

2 

SP 

> STACKPOINTER; STACKPOINTER - .STACK(LENGTH(STACK)); 

00328 

2 



00329 

2 

SBP 

• LENGTH(SBOFF); 

00330 

2 


/* SET OP THE SOURCE FILE •/ 

00331 

2 


CALL HOVE(FCBA,.SFCB,33); 

00332 

2 


CALL MOVE(.('HEX',0)..SFCB(9),4); 

00333 

2 


CALL SEARCH(.SFCB); 

00334 

2 


IF (RFLAG :> DCNT ■ 255) THEN 

00335 

2 


CALL PRINT(.'SOURCE IS READERS'); ELSE 

00336 

2 


DO; CALL PRINT(.'SOURCE IS DISKS'); 



00337 3 

00336 3 

E$') ; 
00339 3 

00340 2 

00341 2 

00342 2 

00343 2 

00344 2 

00345 2 

00346 2 

00347 2 

00348 2 

); ELSE 
00349 2 

00350 3 

00351 3 

) ; 

00352 3 

00353 2 

00354 2 

00355 2 

00356 2 

00357 2 

00358 2 

00359 1 

00360 1 


CALL OPEN(.SFCB)? 

IF DCNT « 255 THEN CALL PRINT(•'-CANNOT OPEN SOURC 

END? ^ 

CALL CRLF? ^ 

CALL MOVE(.'COM',FCBA+9,3); 

/* REMOVE ANY EXISTING FILE BY THIS NAME */ 

CALL DELETE(FCBA)? 

/* THEN OPEN A NEW FILE 

CALL MAKE (FCBA) ; FCB(32) - 0; /* CREATE AND SET NEXT RECORD V 

IF DCNT « 255 THEN CALL PRINT(.'NO MORE DIRECTORY SPACE$' 

DO; CALL RELOC; 

CALL CLOSE(FCBA); 

IF DCNT « 255 THEN CALL PRINT(.'CANNOT CLOSE FILE$ 
END; 

CALL CRLF; 

/* RESTORE STACKPOINTER FOR RETURN */ 

STACKPOINTER « SP; 

RETURN 0; 

END LOADCOM; 

• 

EOF 



